================================================================
 SIMPLE CAMERA  -  Free Cam & Cinematic Photo Mode for GTA V
 by crxhvrd
================================================================

A free-camera and photo-mode plugin for Grand Theft Auto V, built on
ScriptHookV. Detach the camera from your character and fly anywhere to
frame screenshots and cinematic shots.

For motion, switch to CAMERA SEQUENCE mode to author smooth keyframed
camera moves, then play them back live or render them out to an image
sequence for video.

Works in Story Mode and is FiveM-aware (time/weather use the correct
network natives when running under FiveM).


----------------------------------------------------------------
 REQUIREMENTS
----------------------------------------------------------------

  - Grand Theft Auto V (the build supported by your ScriptHookV,
    i.e. the classic/legacy version of the game).
  - ScriptHookV by Alexander Blade  (http://www.dev-c.com/gtav/scripthookv/)
  - OPTIONAL, only for rendering / advanced photo tools:
    ReShade (with add-on support) + the IgcsConnector add-on.


----------------------------------------------------------------
 INSTALLATION
----------------------------------------------------------------

  1. Install ScriptHookV if you don't already have it. This places
     dinput8.dll and ScriptHookV.dll in your GTA V folder (the folder
     that contains GTA5.exe).

  2. Copy  SimpleCamera.asi  into that same GTA V root folder.

  3. (Optional) Copy  SimpleCamera.ini  next to it to change the menu
     key or pre-set defaults. If it's missing, built-in defaults are
     used and the file is created when you save.

  4. Launch the game and press F5 to open the menu.

  The .ini, SimpleCamera_Sequences.ini, and any rendered frames
  (SimpleCamera_Captures\) are all created next to the .asi.


----------------------------------------------------------------
 QUICK START
----------------------------------------------------------------

  1. Press F5 to open the menu, then set the top row "Camera Mode" to
     "Free Camera".
  2. The flycam engages immediately (HUD and your character auto-hide).
  3. Fly with WASD, look with the mouse, raise/lower with Space / Ctrl.
  4. Press F5 again any time to open the settings menu and tweak the
     shot.
  5. Close the menu and compose. Press F10 to save a clean frame
     (needs the ReShade add-on), or use your normal screenshot key.
  6. To leave the flycam, open the menu and set Camera Mode -> Off.


----------------------------------------------------------------
 CONTROLS
----------------------------------------------------------------

FREE CAMERA - Keyboard & Mouse
  F5 .................... Open / close menu
  W / A / S / D ......... Move forward / left / back / right
  Space / Ctrl .......... Move up / down
  Mouse ................. Look
  Q / E ................. Roll left / right
  + / -  (or numpad) .... Zoom in / out (FOV)
  Mouse wheel up/down ... Adjust fly speed
  Hold Shift ............ Speed boost (turbo)
  Hold Alt .............. Precision / slow

FREE CAMERA - Controller
  LB + RB ............... Open menu
  LB + B ................ Exit flycam (camera off)
  Left stick ............ Move
  Right stick ........... Look
  RT / LT ............... Up / down
  LB / RB ............... Roll
  D-Pad Up / Down ....... Zoom (FOV)

MENU NAVIGATION
  Keyboard:   Arrows = move/adjust,  Enter = select,  Bksp = back
  Controller: D-Pad  = move/adjust,  A     = select,  B    = back

CAMERA SEQUENCE HOTKEYS (in Sequence mode)
  F6 .................... Capture current pose as a keyframe
  F7 .................... Play
  F8 .................... Stop
  F9 .................... Jump to next pose

  (The menu key and the four sequence hotkeys are all configurable
   in the INI.)


----------------------------------------------------------------
 FEATURES
----------------------------------------------------------------

  - FREE CAMERA - 6-DOF flight (keyboard / mouse / controller) with
    Euler or Quaternion "Acrobatic" rotation, a momentum-based Drone
    mode, Walk mode, optional collision, Follow / Entity Lock, and Auto
    Drive for filming a self-driving car.
  - PHOTO & SCENE - depth of field, procedural camera shake, time-of-day
    and weather, slow motion and world freeze, and HUD / player hiding.
  - CAMERA SEQUENCE - keyframed camera moves with easing and spline
    paths, an effect-event track, entity lock, multi-vehicle recording
    synced to the timeline, and offline render to an image sequence with
    motion blur.
  - QUALITY OF LIFE - full controller support, INI-persisted settings,
    and sequences that save and reload automatically.

Every option has an in-game tooltip explaining what it does, so the menu
is self-documenting - this readme sticks to setup and the bigger-picture
workflows.


----------------------------------------------------------------
 THE MENU
----------------------------------------------------------------

Press F5 to open. The top row "Camera Mode" switches between Off, Free
Camera, and Camera Sequence - selecting a mode engages it immediately,
and it stays active when you close the menu. Set it to Off to put the
camera away.

Each submenu is documented by its own in-game tooltips; in brief:

  FREE CAMERA ...... Movement (speed, rotation style, drone / walk,
                     follow target), Lens, Depth of Field, Camera
                     Effects (shake), World & Scene, and Misc.
  CAMERA SEQUENCE .. Playback controls, Pose Keyframes, Effect Events,
                     Vehicle Clip recording, Follow & Entity Lock,
                     Sequences, and Render to Images.

  To leave either mode, set the top "Camera Mode" row to Off (Camera
  Sequence can also switch straight to Free Camera).


----------------------------------------------------------------
 WORKFLOWS
----------------------------------------------------------------

Everything in Simple Camera serves one of two goals: a STILL PHOTO or
a MOVING SHOT. The recipes below walk each one start to finish.

Golden rule: F5 opens the menu, and the camera keeps living while the
menu is open - so you compose with the menu up, then close it (F5 /
Backspace) for a clean frame. Closing the menu does NOT exit the flycam;
set Camera Mode -> Off for that.


A. PHOTO MODE - capturing a still
---------------------------------
  1. ENTER. Press F5 and set Camera Mode -> Free Camera. The flycam
     engages and the HUD + your character auto-hide.
  2. GET TO THE SPOT. Fly with WASD + Space/Ctrl, look with the mouse.
     Hold Shift to cover ground fast, Alt for slow precise framing. Mouse
     wheel changes base fly speed. If you clip into geometry, turn on
     Movement -> World Collision.
  3. FRAME THE SHOT. Set focal length in Lens settings -> Lens Zoom (FOV)
     (low FOV = telephoto/compressed, high = wide). Lens Tilt (Roll) for
     a dutch angle; Misc -> Level Horizon snaps roll back to 0.
  4. LIGHT THE SCENE. World & Scene -> Time & Weather: set Time of Day
     (and Pause Time so it won't drift), pick a Weather, or blend two.
  5. FREEZE THE MOMENT. To catch action, use World & Scene -> Freeze All
     Entities (actors stop, camera + particles stay live) or Slow Motion.
     Pause Game halts everything (you can't fly while it's on).
  6. ADD DEPTH. Turn on Depth of Field. Use Auto-Focus to lock onto
     whatever's under screen center, or set Manual Focus Dist. + ranges.
  7. CAPTURE. Close the menu for a clean frame, then shoot with your
     normal screenshot key, ReShade, or F10 (saves a PNG to
     SimpleCamera_Captures\, requires the ReShade add-on).
  8. LEAVE. Open the menu and set Camera Mode -> Off (or controller
     LB+B) to give the camera back to the player.


B. FOLLOWING / FILMING A MOVING SUBJECT
---------------------------------------
Two ways to keep a moving car/ped in your shot:

  - MAKE THE SUBJECT DRIVE ITSELF - Auto Drive. Get in a car, drop a map
    waypoint (or use Drive Anywhere), then World & Scene -> Auto Drive ->
    Enabled. The AI drives; you fly the camera around it. Tune Speed and
    Driving Style.

  - LOCK THE CAMERA TO THE SUBJECT - Follow / Entity Lock. In Movement ->
    Follow Target, choose Player or Aimed Entity (aim at a vehicle/ped and
    lock on). The camera rides along:
      * Rigid Mode OFF - camera holds a fixed world orientation but moves
        with the subject's position.
      * Rigid Mode ON  - camera is bolted on (orbits + rotates with the
        subject), like a hood cam.

Combine them: enable Auto Drive so a car drives a route, then lock the
camera to that car for a hands-free tracking shot.


C. CINEMATIC CAMERA MOVE (sequence)
-----------------------------------
  1. ENTER. Press F5 and set Camera Mode -> Camera Sequence. An empty
     sequence is created; you can free-fly while the menu is open.
  2. LAY DOWN KEYFRAMES. Fly to your opening pose, press F6 (Capture
     Current Pose). Fly to the next position/angle/zoom, press F6 again.
     Repeat for each beat of the move.
  3. SHAPE THE MOTION. Open "Pose Keyframes..." to adjust each keyframe's
     time, easing (Ease-In-Out for smooth starts/stops, Hold to pause on
     a pose) and path type (Spline for flowing curves, Linear for
     straight dolly moves).
  4. AUTOMATE EFFECTS (optional). In "Effect Events...", schedule changes
     along the timeline - shake on/off or strength, or ramp World Speed
     for a slow-mo beat. Mark an event "ramp" to ease between values.
  5. LOCK TO A SUBJECT (optional). To make the whole move ride with a
     vehicle: lock onto it in Free Camera first (Follow Target -> Aimed
     Entity), then in the Sequence menu use "Follow & Entity Lock... ->
     Apply Lock to All". Rigid off = keyframes travel with the car;
     rigid on = they orbit it.
  6. PREVIEW & REFINE. F7 plays, F8 stops, F9 jumps to the next pose.
     Tune Speed and Loop. For a seamless repeat use "Close Loop" (it
     reports the gap between the first and last keyframe).
  7. CLEAN UP. Turn "Show Markers" off so the keyframe spheres and path
     line don't appear in the footage.
  8. SAVE. "Save All to INI" persists your sequences to
     SimpleCamera_Sequences.ini between sessions.


D. FROM SEQUENCE TO FINISHED VIDEO
----------------------------------
  1. Build and save a sequence (Workflow C).
  2. Enable the "IgcsDOF" technique in the ReShade menu (required - see
     RENDERING AN IMAGE SEQUENCE below).
  3. "Render to Images..." -> set FPS / motion blur / format ->
     Start Render. Frames land in SimpleCamera_Captures\render_NNNN\.
  4. Assemble the frames into a video at the SAME FPS in your editor, or
     with ffmpeg:
       ffmpeg -framerate 30 -i frame_%06d.png -c:v libx264 -crf 16
         -preset slow -pix_fmt yuv420p -color_range tv -colorspace bt709
         -movflags +faststart out.mp4
     (The color flags keep contrast matching the rendered frames.)


E. IGCS DEPTH OF FIELD (cinematic bokeh)
----------------------------------------
IGCS Depth of Field (IgcsDof, by Frans Bouma / Otis_Inf) is a far higher-
quality depth of field than the in-game one. Instead of a post-process
blur, it nudges the camera to many tiny offsets and blends the results,
simulating real lens optics - true photographic bokeh with proper
highlights. Simple Camera acts as the "camera tools" it drives. This is
for a SINGLE hero still, not video.

Prerequisites: ReShade (add-on support) + the IgcsConnector add-on, with
the IgcsDof.fx shader present (same as for rendering). Works in FREE
CAMERA mode only (the IGCS link is disabled in Camera Sequence mode).

  1. FRAME THE SHOT in Free Camera. Compose precisely - once the session
     starts you can't move the camera. You DON'T need to freeze the scene
     yourself: Simple Camera automatically slows the world to 1% for the
     duration of the session, so peds/vehicles/cloth/particles barely
     move between samples while the camera + rendering stay live. (Don't
     use Pause Game - it freezes the camera too and breaks the session;
     Freeze All Entities doesn't help either, since animations keep
     playing.)
  2. AVOID CONFLICTS. Turn Simple Camera's own Depth of Field OFF (Depth
     of field -> Depth of Field) so the two don't fight, and DISABLE the
     game's TAA / anti-aliasing - the multi-frame blend does its own AA
     and TAA ghosting will smear the result.
  3. OPEN RESHADE (Home), confirm the "IgcsDOF" technique is enabled,
     then Add-ons tab -> IGCS Connector -> "Start depth-of-field
     session". Simple Camera hands camera control to the add-on (your
     flight input is locked for the duration - expected).
  4. SET FOCUS. Drag "Focus delta" until the in-focus plane lands on your
     subject; enable "Show magnifier" and check a fine detail (e.g. the
     eyes) to confirm it's razor-sharp. "Max bokeh size" sets blur
     strength.
  5. SHAPE THE BOKEH (optional). Circular (points-in-innermost-ring +
     number-of-rings) or aperture-shaped (vertices / rounding / rotation),
     plus Highlight boost/gamma, anamorphic factor, fringing, cat-eye,
     etc. More rings = smoother bokeh but many more frames to render.
  6. TUNE FRAME TIMING if needed. Start with frames-in-flight = 1 and
     frames-to-wait = 0. If the IN-FOCUS area comes out soft, cancel,
     raise frames-in-flight to 2-3, and retry.
  7. RENDER. Click "Start render" and let the blend finish (progress bar).
  8. SAVE, THEN END. Press PrintScreen to save via ReShade FIRST, THEN
     click "End session" - ending discards the blended image.

Full tool manual & controls: https://opm.fransbouma.com/igcsdof.htm


TIPS & TECHNIQUES
-----------------
  - Drone mode (Movement -> Movement Style): weighty, momentum-based
    motion with auto-banking - great for organic fly-throughs.
  - Walk mode pins the camera to a fixed eye height above the ground.
  - Acrobatic (Quaternion) rotation removes the gimbal limit for free
    roll/pitch and FPV-style moves.
  - Procedural shake (Camera Effects) adds life to static shots; speed-
    coupling makes it react to camera motion.
  - Save Position on Exit (Misc) lets you toggle the flycam off/on
    without losing your spot.
  - Info Overlay (World & Scene) shows live position/rotation/FOV.


----------------------------------------------------------------
 RENDERING AN IMAGE SEQUENCE
----------------------------------------------------------------

Camera Sequence mode can render your move out to a numbered folder of
image files - ideal for a clean, stutter-free clip in a video editor.

  1. Requires ReShade (with add-on support) + the IgcsConnector add-on.
     The menu shows a warning if the add-on isn't detected.
  2. Enable the "IgcsDOF" technique (the IgcsDof.fx shader) in the
     ReShade in-game menu - frame capture is routed through it, so
     rendering produces no/black frames if it's left off. (Copy
     IgcsDof.fx into your ReShade shaders folder if it isn't there,
     then tick IgcsDOF in the ReShade menu.)
  3. In the Sequence menu open "Render to Images..." and set:
       - Output FPS and Flush Frames (extra clean frames before each
         grab).
       - Motion Blur samples (up to 128) and Highlight Boost for
         cinematic blur.
       - Format (PNG lossless or JPEG + quality) and optional World
         Slow-mo.
       - Color Channels - leave on Auto. If rendered frames come out
         with red/blue swapped (orange sky, blue road lines), force
         RGBA or BGRA here; some setups (e.g. FiveM) use a different
         buffer format than vanilla.
  4. Choose "Start Render". Frames are written to
     SimpleCamera_Captures\render_NNNN\ next to the .asi.
  5. Import the image sequence into your editor at the same FPS.

  Press F10 at any time in Free Camera for a quick single-frame capture
  test (also via the ReShade add-on).


HOW THE RENDER WORKS
--------------------
The renderer keeps the WORLD alive and in sync with the camera. The
sequence actually PLAYS at a slow time scale, so the camera, the world,
shake and effect events all advance on the SAME game clock and stay in
lockstep. A frame is grabbed each time playback crosses the next 1/fps
mark, so world motion matches camera speed exactly - moving traffic,
pedestrians, your Auto-Drive car, physics, water and particle effects
all render correctly.

   - Motion blur accumulates several CONSECUTIVE LIVE frames per output
     frame (set by Motion Blur samples, up to 128), so it blurs the
     WHOLE moving scene, not just the camera move. Highlight Boost lifts
     the brightness of blur streaks.
   - World Slow-mo set to Auto lets the renderer tune the time scale each
     frame to keep capture in sync; or pin a fixed value.


----------------------------------------------------------------
 RESHADE / IGCS CONNECTOR
----------------------------------------------------------------

Simple Camera implements the IGCS Connector protocol, so ReShade's
IgcsConnector add-on can read the camera's live position/rotation/FOV
and drive its advanced photo features (e.g. multi-shot / high-resolution
captures and DoF sessions). When such a session is active, Simple Camera
hands camera control to the add-on so the two never fight.

The same shared channel powers F10 single-frame capture, the image-
sequence renderer, and IGCS Depth of Field (the multi-frame optical bokeh
tool - see Workflow E above). For any of these you must also enable the
"IgcsDOF" technique (IgcsDof.fx) in the ReShade in-game menu - capture is
routed through that shader. None of the core free-camera features need
ReShade - it is only required for capture/render and IGCS tooling.

Credit: the IGCS Connector add-on and IgcsDof shader are by Frans Bouma
(Otis_Inf). Full DoF manual: https://opm.fransbouma.com/igcsdof.htm


----------------------------------------------------------------
 CONFIGURATION FILE (SimpleCamera.ini)
----------------------------------------------------------------

Lives next to the .asi. Holds the menu key and all saved tunables.
Key codes use Windows virtual-key codes:
https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes

  [Controls]
  ; Menu toggle key (default: F5 = 116)
  MenuKey=116
  ; Camera Sequence hotkeys
  SequenceAddKey=117    ; F6 - capture pose
  SequencePlayKey=118   ; F7 - play
  SequenceStopKey=119   ; F8 - stop
  SequenceNextKey=120   ; F9 - next pose

Camera, Drone, Shake, DoF and Misc settings are written under their own
sections when you choose "Save Settings to INI" in the Misc menu.
"Reset to Defaults" restores factory values (save afterward to persist).


----------------------------------------------------------------
 TROUBLESHOOTING
----------------------------------------------------------------

  - Menu won't open on F5:  Make sure ScriptHookV is installed and up to
    date for your game version, and SimpleCamera.asi is in the GTA V
    root folder. Confirm MenuKey in the INI isn't bound elsewhere.

  - "Needs ReShade + IGCS addon" on Start Render:  The renderer and F10
    capture need ReShade (add-on support) plus the IgcsConnector add-on.
    Core free-cam features work without them.

  - Render runs but the frames are black / empty:  The "IgcsDOF"
    technique (IgcsDof.fx) must be ENABLED in the ReShade in-game menu -
    capture is routed through it. Tick it on and render again.

  - Camera clips through walls:  Enable "World Collision" in the
    Movement menu (off by default so flight stays unobstructed).

  - Time/weather won't stick in FiveM:  The mod auto-detects FiveM and
    uses network override natives; a server that actively re-syncs
    time/weather may override it.

  - Acrobatic (Quaternion) rotation needs a model to stream in:  On the
    very first frames it briefly falls back to standard rotation while a
    tiny invisible anchor prop loads. This is normal.


----------------------------------------------------------------
 CREDITS & LICENSE
----------------------------------------------------------------

  Author:  crxhvrd
  Built on ScriptHookV by Alexander Blade.
  Photo-capture / IGCS interop via the IgcsConnector ReShade add-on.

  Released under the MIT License (see LICENSE).

================================================================
